\input macros
\def\bookline{\CLOS\  Specification}
\def\chapline{Basic User Interface Functions}

\beginChapter 2.{Common Lisp Object System Specification}%
{Basic User Interface Functions}{Basic User Interface Functions}

Contributors to this document include Daniel G. Bobrow, Linda G.
DeMichiel,\break Richard P. Gabriel, Kenneth Kahn, Sonya E. Keene,
Gregor Kiczales, Larry\break Masinter, David A. Moon, Mark Stefik, and
Daniel L. Weinreb.

Comments and suggestions on this document are encouraged.
Changes will be incorporated over the next several months.
This text will be made available to the X3J13 Committee for the
Common Lisp Standards effort.

\endTitlePage

\beginSection{Introduction}
This chapter describes the functions provided by
the \CLOS\ Basic User Interface.
\vfill
\endSection%{Introduction}


\begincom{add-method}

\label Purpose:

The function {\bf add-method} adds a method to a generic function.  It returns
the modified generic function as its result.

\label Syntax:

\Defun {add-method} {generic-function qualifiers specializers function}

\label Arguments:

The {\it generic-function\/} argument is a generic function or the name
of a generic function.

The {\it qualifiers\/} argument specifies the method combination options.

The {\it specializers\/} argument is a list of argument specializers of
the type that may be given to {\bf defmethod}.

The {\it function\/} argument is the method function.

\label Values:

The modified generic function is returned as the result of {\bf add-method}.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label See Also:

{\bf defmethod

make-generic-function}

\endcom


\begincom{argument-precedence-order}

\label Purpose:

The function {\bf argument-precedence-order} returns two values: a
list of the required parameters of the generic function, in the order in which
they were specified, and a list of these same parameters, in order of
decreasing precedence.

\label Syntax:

\Defun {argument-precedence-order} {generic-function}

\label Arguments:

The {\it generic-function\/} argument is a generic function or the name
of a generic function.

\label Values:

Two values are returned: a list of the required parameters of the generic
function and a list of the same parameters, in order of decreasing
precedence.

\label Examples:

\screen!

[To be written.]
\endscreen!

\endcom


\begincom{call-next-method}

\label Purpose:

{\bf call-next-method} is used within the body of a method.  It calls
the `next method' with the same arguments that this method received.

For the precise definition of `next method,' see the section ``Method 
Combination.''  {\bf call-next-method} returns the value or values
returned by the method it calls.  Further computation after {\bf
call-next-method} returns is possible, so this provides a general
imperative form of method-combination.

The type of method combination in use determines which kinds of methods
allow {\bf call-next-method} to be used.  The default method combination
type, {\bf :daemon}, allows {\bf call-next-method} to be used inside
primary methods and {\bf :around} methods.  If you define a new type of
method combination using the simple form of {\bf define-method-combination}, 
{\bf call-next-method} can be done in {\bf :around} methods only.

\label Syntax:

\Defun {call-next-method} {}

\label Arguments:

{\bf call-next-method} is called with no arguments.

\label Values:

{\bf call-next-method} returns the value or values returned by the
method it calls. 
 
\label Remarks:

If {\bf call-next-method} runs out of methods, it signals an error. 

The exact definition of `same arguments' is still under discussion and must
be clarified.  This is particularly complicated in the face of optional,
rest, and keyword parameters.  {\bf call-next-method} passes the actual values of
the parameter variables to the next method, except for keyword parameters,
which are passed via a rest-argument, not individually.  Thus defaulted
optional parameters cannot be defaulted again by the next method, but
keyword parameters can be re-defaulted by the next method.  If a parameter
variable is {\bf setq}'ed, or another variable with the same name is bound, the
variable value visible at the lexical position of the {\bf call-next-method} form
is used.

Possible extensions:

{\bf call-next-method} {\it arguments\/}  When at least one argument is
given, {\bf call-next-method} supplies those
arguments instead of the arguments that this method received.  

{\bf apply-next-method} {\it arguments\/} This is like {\bf
call-next-method} except that it uses {\bf apply} instead of {\bf
funcall}.  That is, the last argument is really a list of arguments.

\label See Also:

See the sections ``Method Selection'' and ``Method Combination.''

\endcom



\begincom{change-class}

\label Purpose:

The function {\bf change-class} changes the class of an instance to the
new class.  It destructively modifies and returns the instance.

\label Syntax:

\Defun {change-class} {instance new-class}

\label Arguments:

The {\it instance\/} argument must be an instance whose metaclass is
{\bf class}.  % (a standard object)

The {\it new-class\/} argument is a class object.

\label Values:

The modified instance is returned.  The result of {\bf change-class}
is {\bf eq} to the {\it instance} argument.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

[The internal protocol of {\bf change-class} needs to be spec'd.]

\endcom



\begincom{class-of}

\label Purpose:

The function {\bf class-of} returns the most specific class of which the 
given object is an instance.   Every Common Lisp object has a class.  

\label Syntax:

\Defun {class-of} {object}

\label Arguments:

The argument to {\bf class-of} may be any Common Lisp object.

\label Values:


\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

If the object was created with {\bf make-instance} and its class was
not changed, the class that is
returned is the class that was specified as the {\it class\/} argument 
of {\bf make-instance}.

If the object was created with a constructor defined by {\bf defstruct}, 
the class that is returned is the class with the same name as the data
type defined with the {\bf defstruct} form.

If the object is an instance of a class whose class is {\bf
standard-type-class} or a subclass of {\bf standard-type-class} (other
than a class created with {\bf defstruct}), the class that is returned
is the most specific class according to Figure~1-2.

Note that {\bf class-of} can never return an abstract class.

\endcom



\begincom{defclass}

\label Purpose:

The macro {\bf defclass} defines a new class, which is a template of a
new data type with named slots.  It returns the name of the new class as 
its result.

{\bf defclass} syntax offers options that allow for providing default
initialization of the slots, and for requesting that functions be 
automatically generated to read and write the values of the slots, or to
construct new instances.   By default, no accessor, reader, constructor,
or predicate function is defined.   Also, slots are not by default
initable. 

When you define a class you are also defining a type.  That is, 
({\bf typep} {\it object class-name\/})  
is true if the object is an instance of the given class.

\label Syntax:

[Note:   can you put the following Syntax description into the box format?]

(defclass class-name ({super-class-name}*) ({slot-spec}*) {class-option}*)

class-name ::= a non-null symbol

super-class-name ::= a non-null symbol

slot-spec ::=  slot-name | 
               (slot-name default-value) |
               (slot-name {slot-option}*) 

slot-option ::= :default-value form |
		:accessor generic-function-name |
		:reader generic-function-name |
		:initable keyword |
		:allocation allocation-type |
		
allocation-type ::= :instance | :class | :none | :dynamic 

class-option ::= (:documentation string) |
                 (:accessor-prefix string-or-symbol) |
		 (:reader-prefix string-or-symbol) |
		 :initable-slots |
		 (:metaclass class-name) |
		 (:instantiable t-or-nil) 
		 (:predicate symbol) 
		 (:constructor symbol [boa-arglist]) 

boa-arglist ::= as you have it below 

\cboxfig{
\leftskip 2pc
\cleartabs\settabs\+\hskip\leftskip&\cr
\+&{\bf defclass} {\it class-name includes} \paren{\star{\curly{slot-description}}} \star{\curly{class-option}}\cr
\Vskip 1pc!
\+&{\it includes\/}::$=$ (\star{\curly{class-name}})\cr
\Vskip 1pc!
\+&{\it class-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&\cleartabs{\it slot-description\/}::$=$ &{\it slot-name\/} $\vert$ ({\it slot-name\/} \brac{initform \star{\curly{slot-option}}})\cr
\Vskip 1pc!
\+&\cleartabs{\it slot-option\/}::$=$ &{\tt :initialize-only} {\it flag\/} $\vert$\cr
\+&&{\tt :accessor} {\it generic-function-name\/} $\vert$ {\tt :accessor nil} $\vert$ \cr
\+&&{\tt :read-accessor} {\it generic-function-name\/} $\vert$ {\tt :read-accessor nil} $\vert$ \cr
\+&&{\tt :allocation} {\it allocation-type} \cr
\Vskip 1pc!
\+&{\it generic-function-name\/}::$=$ {\it symbol\/}\cr
\Vskip 1pc!
\+&{\it allocation-type\/}::$=$ {\tt :instance $\vert$ :class $\vert$ :dynamic $\vert$ :none}\cr
\Vskip 1pc!
\+&\cleartabs{\it class-option\/}::$=$ &({\tt :accessors-with-prefix} {\it string-or-symbol\/}) $\vert$\cr
\+&&({\tt :readers-with-prefix} {\it string-or-symbol\/}) $\vert$\cr
\+&&{\tt :constructor} $\vert$ ({\tt :constructor} {\it symbol\/}) $\vert$ ({\tt :constructor nil}) $\vert$\cr
\+&&({\tt :constructor} {\it symbol boa-arglist\/}) $\vert$\cr
\+&&{\tt :predicate} $\vert$ ({\tt :predicate} {\it symbol\/}) $\vert$ ({\tt :predicate nil}) $\vert$\cr
\+&&({\tt :metaclass} {\it class-name\/}) \cr
\+&&({\tt :instantiable t}) $\vert$ ({\tt :instantiable nil}) \cr
\+&&({\tt :documentation} {\it string\/})\cr
\Vskip 1pc!
\+&\cleartabs{\it boa-arglist\/}::$=$ (& \star{\curly{symbol}}\cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var \ttbrac{initform} {\rm )}}}}  \cr
\+&&\ttbrac{{\rest} {\it var}}\cr
\+&&\ttbrac{{\tt\&aux} \star{\curly{var $\vert$ {\rm (}var \brac{initform}{\rm )}}}}{\rm )}\cr
}
\caption{Syntax for defclass}
\endfig

\vfill\eject

\label Arguments:

{\it class-name\/} is a non-null symbol that names the class being
defined.  If a class is already defined with this name, this definition
replaces the old definition.

Each {\it slot-spec\/} includes the name of the slot, which is a
non-null symbol.   The {\it slot-name\/} can be given alone, or in a list.   

{\it slot-spec\/} can be a list of the slot name and its {\it
default-value\/}, which can be any form.  When an instance is made and
no initial value for this slot is provided as an argument to {\bf
make-instance}, the slot is initialized to the value of this form.  The
{\it default-value\/} is evaluated every time it is used. 

{\it slot-spec\/} can also be a list of the {\it slot-name\/} followed
by one or more {\it slot-options\/}, each of which 
specifies an option that is specific to this slot.  

The defined {\it slot-options\/} are:

{\bf :default-value} {\it form\/} This is an alternate way for providing
a default initial value form.  The {\it form\/} is evaluated every time it is
used.  

{\bf :accessor} {\it generic-function-name\/} This specifies that a
method for an accessor function should automatically be generated for
this slot.  An accessor is used to to read the value of this slot, and
{\bf setf} may be used with it to write the value of the slot.  {\it
generic-function-name\/} must be a non-null symbol.

{\bf :reader} {\it non-null-symbol\/} This specifies that a method for a
reader function should automatically be generated for this slot.  The
reader is a generic function named {\it non-null-symbol\/}.  A reader is
used to read the value of the slot.   This option does not cause a {\bf
setf} function to be defined.  {\it generic-function-name\/} must be a
non-null symbol.

{\bf :initable} {\it keyword\/} This specifies a keyword to be used to
specify an initial value of this slot, when a new instance is being
made.  {\it keyword\/} must be a non-nil symbol.

{\bf :allocation} {\it allocation-type} This specifies where storage is
allocated for this slot.  The {\it allocation-type\/} can be one of 
these keywords: {\bf :instance}, {\bf :class}, {\bf :dynamic}, {\bf :none}.  The
semantics of these keywords are:

{\bf :instance} Storage is allocated in the instance itself; each
instance has its separate value for this slot.  This is the default.

{\bf :class} Storage is allocated in the class.  Thus a single value for
this slot is shared by all instances.  The exact semantics of {\bf
:class} are still under discussion.  For example, how are subclasses
handled?  Does each subclass have a separate copy of this slot, or do
all subclasses share the same copy?

{\bf :dynamic} This option is still under discussion; it is not yet 
clear whether it should be in the standard.  The purpose of this option
is to specify:  Storage is allocated in the instance at the time of the
first use of the slot.  If the slot is initialized with a keyword
argument to {\bf make-instance}, the slot is allocated then.  If the
first access is a read, then storage is allocated and the default value
declared in the {\bf defclass}, if any, is stored in the slot and
returned.  If the first access is a {\bf setf}, then storage is
allocated and the value is stored in the slot and returned.  This option
allows infrequently-used slots to take storage only when necessary.

{\bf :none} No storage is to be allocated; the slot should not exist in
instances of this class.  This is used to override inheritance of slots
defined by a super-class.

Each {\it super-class-name\/} is a non-null symbol naming a class to be
included as an integral part of this class.  The class now being defined
will inherit characteristics (such as slots) and behavior (such as
methods) from each of its super-classes.  Each {\it super-class-name\/}
must refer to a user-defined class, not a  built-in class.  A built-in 
class corresponds to one of the predefined Common Lisp type specifiers;
for example {\bf array} is a built-in class for objects of type {\bf array}.

Each {\it class-option\/} is an option that refers to the class.
The set of defined options is:

(:documentation string) This enables you to specify an arbitrary string
as documentation for this class.  The form (documentation class-name
'type) retrieves this string.

(:instantiable t-or-nil) This option has not been discussed.
This specifies whether it is possible to directly
instantiate this class with {\bf make-instance}.  If {\bf :instantiable} is
{\bf nil}, the class cannot be instantiated and is termed an {\bf abstract 
class}.  The default value of {\bf :instantiable} is {\bf t}.

(:predicate symbol)  This option has not been discussed yet.  This
generates a predicate function named {\it symbol\/}, which must be a
non-nil symbol.   The predicate function takes one argument, an object,
and returns {\bf t} if the object is of this class, {\bf nil} otherwise.  

(:accessor-prefix string-or-symbol) This causes a method for an accessor
generic function to be generated automatically for each slot.  
The accessor is used to read the value of a slot and can be
used with {\bf setf} to write the value of a slot.  The name of each 
accessor is the prefix {\it string-or-symbol\/} followed by the name of
the slot.

(:reader-prefix string-or-symbol) This causes a method for a reader
generic function to be generated automatically for each slot.  The
reader is used to read the value of a slot.  This option does not cause
a {\bf setf} function to be defined.  The name of each reader is the
prefix {\it string-or-symbol\/} followed by the name of the slot.

:initable-slots This specifies that it is allowed to initialize all
slots of this class.  The initialization can be done by providing the
keyword with the same name as the slot, followed by the slot's initial
value as an argument to {\bf make-instance}, or by including the keyword
and value in the {\bf :default-init-plist}.

(:default-init-plist {keyword argument}*) This option is still under
discussion; it is not yet clear whether it will be in the standard.  The
purpose of this option is to:  Set up defaults that are used when making 
an instance.   For example, a class might specify a default value to 
use to initialize a slot inherited from one of its super-classes. 
Each {\it keyword\/} must be a valid keyword argument to
{\bf make-instance}.  Each {\it argument\/} is a form that provides the default
value for that keyword argument if it is not supplied.  The user can
override the defaults in the {\bf :default-init-plist} by providing
keyword arguments to {\bf make-instance}.  The {\it arguments\/} are evaluated
every time they are used.

(:init-keywords {keyword}*) This option is still under discussion; it is
not yet clear whether it should be in the standard.  The purpose of this
option is to:  Specify that each given keyword is an allowed keyword
argument to {\bf make-instance} for this class.  There is no need to
provide this argument to make it possible to initialize slots; that is
done with the {\bf :initable-slots} option.  The {\bf :init-keywords}
option is used in conjunction with methods you have written for {\bf
make-instance}.  If a {\bf make-instance} method accepts an argument,
you must explicitly make it an allowed keyword argument to {\bf
make-instance} by using this option.

(:constructor symbol [boa-arglist]) This causes a constructor function
named {\it symbol\/} to be generated automatically.  The constructor is
used to make a new instance of the class.  If no {\it boa-arglist\/} is
present, the constructor takes keyword arguments.  If {\it
boa-arglist\/} is present, it describes the arguments to the
constructor.  The syntax of the {\bf :constructor\/} option to {\bf
defclass} is the same as that of the {\bf defstruct :constructor} option
described in ``Common Lisp the Language.''

(:metaclass class-name) This specifies that this class has a different
implementation than the system-provided default.  If you have invented a
new metaclass, this option is the mechanism for creating classes of that
metaclass.  {\it class-name} is the name of a class that is capable of
being the class of a class.


\label Values:

The name of the new class is returned as the result.

\label Examples:

\screen!

(defclass ship ()
               (name
                (x-velocity :accessor ship-x-vel)
                (y-velocity :accessor ship-y-vel)
                (mass :reader ship-mass))
  :initable-slots)

\endscreen!

\label Remarks:

Each class has a `component classes tree' composed of all its
super-classes, and the super-classes of each of its super-classes, and so
on.  This tree is used to compute the class precedence list of the class.
See the section ``Determining the Class Precedence List.''

Note the following rules of {\bf defclass}:

   - All the component classes of a class must be defined before it is
     permitted to make an instance of the class.

   - A class must be defined before it can be mentioned as an argument
     specifier in a {\bf defmethod}.

   - All component classes of a class must be defined before it is
     permitted to evaluate or compile a {\bf with-slots} that uses this
     class.

Some implementations might add other options to {\bf defclass}.  Therefore it is
required that all implementations signal an error if they observe an option
that is not implemented locally.

If no default value for a slot is specified either in the {\bf defclass} or the
{\bf make-instance} form, the initial value of the slot is undefined and it is an
error to reference it.  This is the same behavior as a {\bf defvar} with no
initial value form.

When the definition of a class changes, each existing instance of the class
is updated to the new format the next time it is accessed.  (Note that this
behavior might be categorized as an optional feature.)

It is valid to specify more than one accessor, reader, and keyword for
initialization, for a single slot.  For example, this can happen when
the {\bf :accessor} slot option is used to specify an accessor for a 
slot, and the {\bf :accessor-prefix} option is used to specify that all 
slots should have an accessor with the supplied prefix. 

If neither a reader nor an accessor is specified for a slot, the slot
can only be accessed by the function {\bf slot-value} or {\bf
with-slots} using {\bf :use-accessors nil}.

\label See Also:

{\bf with-slots}

{\bf slot-value}

See the section ``Determining the Class Precedence List.''

\endcom



\begincom{defgeneric}

\label Purpose:

The macro {\bf defgeneric} defines a generic function and stores it in
the symbol function cell of the symbol that is its name.  The new
generic function object is returned as the result.  {\bf defgeneric} 
allows you to specify options and declarations that pertain to the 
generic function as a whole. 

It is still under discussion whether it should be required that a {\bf
defgeneric} must be evaluated before any methods are defined, or whether
{\bf defmethod} should set up a generic function with default options,
if no {\bf defgeneric} has been evaluated.

\label Syntax:

(defgeneric generic-function-name lambda-list {option}*)

option ::= (:documentation string) | string
           (:method-combination name {argument}*)
           (declare {declaration}+)
           (:argument-precedence-order {parameter-name}+)
           (:interface {form}+)
           (:method-arguments {form}+)
           (:generic-function-class class-name)
           (:method-class class-name) 

\Defmac {defgeneric} {name lambda-list \ttbrac{documentation} \star{\curly{option}}}

{\it option\/}::$=$ {\tt\vtop{\hbox{(:argument-precedence-order {\it argument-precedence-order-list\/}) $\vert$}
\hbox{(:method-combination-type {\it symbol\/}) $\vert$}
\hbox{$\ldots$}}}

\label Arguments:

{\it generic-function-name} is a non-null symbol naming the generic function.

The {\it lambda-list\/} argument is an ordinary function lambda list
with these exceptions:

1.  No \&aux variables are allowed. 
2.  Optionals (including keyword arguments)may not have default-forms ur
    use supplied-p, and hence the symbol does not imply a default value
    of NIL.   Note that optionals in the methods can have default forms
    and supplied-p. 

The set of defined options is:

(:documentation string) | string
                Associates a documentation string with the generic
                function.  The form (documentation generic-function-name
                'function) retrieves this string.

(:method-combination name {argument}*)
                Indicates that the generic function uses the type of method
                combination named by name.  The arguments depend on the
                type of method combination.  The most common argument is
                one to specify the order of methods, which is either
                :most-specific-first or :most-specific-last.  The default
                method combination type is :daemon, with the
                :most-specific-first order.

(declare {declaration}+)
                Declarations that apply to the whole function (as opposed
                to declarations of variables) are permitted.  The only
                declaration in this standard is optimize, which can have
                the value of speed or space.  This allows the user to
                control whether method selection is optimized for speed or
                space; it has no affect on individual methods.  Some
                implementations might support other declarations.  If an
                implementation notices a declaration that it does not
                support, it should follow the rules described on page 161
                of Common Lisp the Language.

(:argument-precedence-order {parameter-name}+)
                This option alters the default way of selecting methods.
                By default, all required arguments are considered
                from left to right; each required argument has
                precedence over those to its right.  When this option is
                used, each required argument should be included as a
                parameter-name, so the full precedence order is supplied.

(:interface {form}+)
		This option is under discussion.
                Defines a function that runs instead of the generic
                dispatch.  This is completely transparent to anyone calling
                the generic function.  Such a prologue function can be used
                to rearrange the arguments, to standardize the arguments
                before the methods see them, to default optional arguments,
                to do the shared non-generic portion of an operation, or
                for any other purpose.  Another use of this option is to
                extend a generic function so it can also be used for
                objects that are not instances of a built-in class.

                Inside the forms you can trigger the generic dispatch with
                (call-methods args...) or (apply-methods args...).
                apply-methods treats the last argument as a list of
                arguments just like apply.  call-methods and apply-methods
                are defined lexically only inside the :interface option.

(:method-arguments {form}+)
		This option is under discussion. 
                You can use this option to specify that the methods accept
                different arguments than does the generic function itself.
                By default, the methods receive the same arguments that are
                specified at the top of the defgeneric form.  The
                :method-arguments option is meaningful only in connection
                with the :inteface option.

(:generic-function-class class-name)
                Specifies that this generic function has a different
                implementation than the system-provided default.  If you
                have invented a new generic function class, this option is
                the mechanism for creating a generic function of the new
                class.  class-name is the name of a class that is capable
                of being the class of a generic function.

(:method-class class-name)
                This is used to specify that all methods for this generic
                function have a different implementation than the
                system-provided default.  If you have invented a new method
                class, this option is the mechanism for creating methods of
                the new class.  Once the defgeneric form with this option
                is evaluated or compiled, any methods you define with
                defmethod will be implemented in the class name specified
                here.  class-name is the name of a class that is capable of
                being the class of a method.

\label Values:

The new generic function object is returned as the result.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

The function and use of {\bf defgeneric} is closely related to the
design of the method combination mechanism and the specification of
discrimination on optional arguments.  The name of {\bf defgeneric} is
subject to change, depending on the results of these decisions.

If a {\bf defgeneric} form is evaluated when a generic function of the
same name is already defined, the new definition replaces the old.

If a {\bf defgeneric} form is evaluated and some methods for that
generic function have parameters that are not congruent with those
listed in the {\bf defgeneric}, an error is signalled.  

Some implementations might add other options to {\bf defgeneric}. 
Therefore it is required that all implementations signal an error if
they observe an option that is not implemented locally.

\endcom




\begincom{defgeneric-setf}

\label Purpose:

{\bf defgeneric-setf} enables you to define a {\bf setf} generic
function.  The new generic function object is returned as the result.

\label Syntax:

(defgeneric-setf generic-function-name lambda-list setf-lambda-list {option}*)

option ::= (:documentation string) | string
           (:method-combination name {argument}*)
           (declare {declaration}+)
           (:argument-precedence-order {parameter-name}+)
           (:interface {form}+)
           (:method-arguments {form}+)
           (:generic-function-class class-name)
           (:method-class class-name) 

\label Arguments:

{\it generic-function-name} is a non-null symbol naming an accessor
generic function.  

The {\it lambda-list\/} argument is the same as for {\bf defgeneric}.

{\it setf-lambda-list} is ({\it variable-name\/}).  {\it
variable-name\/} is the name of the variable that gets bound to the
value {\it foo\/} in ({\bf setf} ({\it name x y z\/}) {\it foo\/}).
Like the variable names in the {\it lambda-list\/} it is only for
documentation. 

The keyword options are the same as for {\bf defgeneric}. 
 
\label Values:

The new generic function object is returned as the result.

\label Examples:

\label Remarks:

\label See Also:

{\bf defgeneric}

\endcom




\begincom{define-method-combination}

\label Purpose:

{\bf define-method-combination} is a mechanism for declaring a new type
of method combination.

At present the details of this function and related functions are under
discussion.    

\label Syntax:

\label Arguments:

\label Values:

\label Examples:

\label Remarks:

\endcom



\begincom{defmethod}

\label Purpose:

The macro {\bf defmethod} defines a new method for performing a generic
function.  It returns the new method as its result.

The argument list of the method must be congruent. with the argument
list of the generic function.  If this condition does not hold, an error is
signalled.  See ``Remarks"'' for a definition of congruency in this
context. 

[The following is under discussion:  A generic function of the given name
must exist before any methods of that name can be defined.]

\label Syntax:

   (defmethod generic-function-name {qualifier}*
              specialized-lambda-list 
     {declaration | doc-string}*
     {form}*)

\Defmac {defmethod} {generic-function-name
\vtop{\hbox{\star{\curly{qualifier}}}
\hbox{specialized-lambda-list}
\hbox{\star{\curly{declaration $\vert$ documentation}} \star\form}}}
\Vskip1pc!\null
{\it generic-function-name\/}::$=$ {\it symbol}
\Vskip1pc!\null
{\it qualifier\/}::$=$ {\tt :before $\vert$ :after $\vert$ $\dots$}
\Vskip1pc!\null
\settabs\+\hskip\leftskip&\cr
\+&{\it specialized-lambda-list\/}::$=$ (&\star{\curly{var  $\vert$ {\rm (}var specializer\/{\rm )}}}  \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var \ttbrac{initform {\brac{supplied-p-parameter}} }{\rm )}}}}  \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var  $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var{\rm )}}
\ttbrac{initform \brac{supplied-p-parameter} }{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} \cr
\+&&\ttbrac{{\tt\&aux} \star{\curly{var $\vert$ {\rm (}var \brac{initform} {\rm )}}}} {\rm )} \cr
\Vskip1pc!\null
\+&{\it specializer\/}::$=$ {\it symbol} $\vert$ {\tt '}{\it datum}\cr
\Vskip 1pc!

\label Arguments:

generic-function-name
                A non-null symbol that names the generic function
                being specialized.   

qualifier       A non-null symbol OR a non-null atom (not agreed yet), used
                by method combination to identify the method.  For
                example, :before, :after, or :around. 

specialized-lambda-list
                A lambda-list as defined in Common Lisp the Language, page
                60, possibly with some required arguments replaced by
                specialized-variables so that method selection uses that 
                argument.  A specialized-variable is a list such as:
                (variable-name parameter-specifier).  A specialized-variable
                may be used wherever a lambda-list allows only a
                variable and not a list.  Only required parameters may 
                be specialized.  [Note that the specialization on optional
                parameters is still under discussion.]
 
parameter-specifier  
 		parameter-specifier can be a user-defined class, or the name 
                of a structure defined by defstruct if the :type option was
                not used, or a Common Lisp type specifier from the subset
                listed here:

                array               integer          ratio
                bit-vector          list             rational
                character           long-float       readtable
                compiled-function   null             sequence
                complex             number           short-float
                cons                package          single-float
                double-float        pathname         string
                float               quote      	     symbol
                hash-table          random-state     t  
                                                     vector

                Note that the use of t as a parameter-specifier defines a
                default method.  Such a method is selected only when no
                more specific method for the generic function is defined.

                Quote is used with an object to indicate that this
                argument must be bound to the quoted object for this 
                method to be applicable. 

\label Values:

The new method object is returned as the result.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

All methods of a generic function must have congruent argument lists.
In this context, congruency implies that the system can determine whether
a call is syntactically correct.   The rules are:

1.  Methods must have the same number of required and optional
arguments.

2.  Methods must allow exactly the same keywords, or use
\&allow-other-keys appropriately.

3.  Either all methods have use \&rest or none of them use it.

\endcom


\begincom{defmethod-setf}

\label Purpose:

The macro {\bf defmethod-setf} defines a {\bf setf} method.

\label Syntax:

   (defmethod-setf generic-function-name {qualifier}*
                   specialized-lambda-list
                   setf-lambda-list
     {declaration | doc-string}*
     {form}*)

\Defmac {defmethod-setf} {generic-function-name
\vtop{\hbox{\star{\curly{qualifier}}}
\hbox{specialized-lambda-list specialized-setf-vars}
\hbox{\star{\curly{declaration $\vert$ documentation}} \star\form}}}
\Vskip1pc!\null
{\it generic-function-name\/}::$=$ {\it symbol}
\Vskip1pc!\null
{\it qualifier\/}::$=$ {\tt :before $\vert$ :after $\vert$ $\dots$}
\Vskip1pc!\null
\settabs\+\hskip\leftskip&\cr
\+&{\it specialized-lambda-list\/}::$=$ (&\star{\curly{var  $\vert$ {\rm (}var specializer\/{\rm )}}}  \cr
\+&&\ttbrac{{\opt} \star{\curly{var $\vert$ {\rm (}var \ttbrac{initform {\brac{supplied-p-parameter}} }{\rm )}}}}  \cr
\+&&\ttbrac{{\tt\&rest} {\it var\/}} \cr
\+&&{\tt [}{\key{}}&\star{\curly{var  $\vert$
{\rm (}\curly{var $\vert$ {\rm (}keyword var{\rm )}}
\ttbrac{initform \brac{supplied-p-parameter} }{\rm )}}}\cr
\+&&&\brac{\tt\&allow-other-keys} {\tt ]} \cr
\+&&\ttbrac{{\tt\&aux} \star{\curly{var $\vert$ {\rm (}var \brac{initform} {\rm )}}}} {\rm )} \cr
\Vskip1pc!\null
\+&{\it specialized-setf-vars\/}::$=$ (\star{\curly{var  $\vert$ {\rm (}var specializer\/{\rm )}}}  \cr
\Vskip1pc!\null
\+&{\it specializer\/}::$=$ {\it symbol} $\vert$ {\tt '}{\it datum}\cr
\Vskip 1pc!

\label Arguments:

The arguments {\it generic-function-name\/}, {\it qualifier\/}, and
{\it specialized-lambda-list\/} are the same as for {\bf defmethod}.

{\it setf-lambda-list\/} is the same as {\it specialized-lambda-list\/}
except that for now there can be only one parameter.  In other words,
{\it setf-lambda-list\/} is a lambda list containing exactly one
required parameter, which may be specialized.  It is either ({\it
variable-name\/}) or (({\it variable-name parameter-specializer\/})).

\label Values:

The new method object is returned as the result.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label See Also:

{\bf defmethod}

\endcom



\begincom{describe}

\label Purpose:

\label Syntax:

\Defun {describe} {object}

\label Arguments:

\label Values:

\label Examples:

\endcom



\begincom{documentation}


\label Purpose:

The Common Lisp function {\bf documentation} is extended as follows:
If the symbol names a generic function, {\bf documentation} returns the
documentation string for the generic function.
If the first argument is a method, the documentation string of the method
is returned.
If the first argument is a class object, the documentation string for the
class is returned.

\label Syntax:

\Defun documentation {symbol doc-type}

\label Remarks:

The macro {\bf setf} can be used with {\bf documentation} to update the
documentation for a symbol, generic function, method, or class.

\endcom



\begincom{function-parameters}

\label Purpose:

The function {\bf function-parameters} returns the lambda list of its
argument from which default values for {\bf \&optional} and {\bf \&key}
parameters and supplied-p parameters have been removed.

\label Syntax:

\Defun {function-parameters} {function-or-generic-function}

\label Arguments:

The argument to {\bf function-parameters} is a function, generic function, or
a symbol that names a function or generic function.

\label Values:

The result of {\bf function-parameters} is a copy of the lambda list of its
argument from which default values for {\bf \&optional} and {\bf \&key}
parameters and supplied-p parameters have been removed.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

[It is intended that this function correspond to whatever
{\bf function-parameters} is adopted for Common Lisp.]

The macro {\bf setf} can be used with {\bf function-parameters}.


\endcom


\begincom{generic-function-method-combination}

\label Purpose:

The function {\bf generic-function-method-combination} returns the method combination
for the given generic function.

\label Syntax:

\Defun {generic-function-method-combination} {generic-function}

\label Arguments:

The {\it generic-function\/} argument is a generic
function or a symbol that names a generic function.

\label Values:

\label Examples:

\screen!

[To be written.]
\endscreen!

\endcom



\begincom{generic-function-p}

\label Purpose:

The predicate {\bf generic-function-p} is true if its argument is a
generic function, otherwise it is false.

\label Syntax:

\Defun {generic-function-p} {object}

\label Values:

A non-{\bf nil} value is returned if the argument is a generic function
object, otherwise the result is {\bf nil}.

\label Examples:

\screen!
\endscreen!

\endcom



\begincom{get-method}

\label Purpose:

The function {\bf get-method} takes a generic function and returns the
method object that has the given argument qualifiers and specializers.
If no such method exists, {\bf get-method} returns {\bf nil}.

\label Syntax:

\Defun {get-method} {generic-function qualifiers specializers}

\label Arguments:

The {\it generic-function\/} argument is a generic function or a
symbol that names a generic function.  An error is signalled if no
such function exists.

The {\it qualifiers\/} argument specifies the method combination options.

The {\it specializers\/} argument is a list of the argument specializers
for the method.  If {\it specializers\/} is {\bf nil}, the
default method function for that generic function is returned.

\label Values:

The result of {\bf get-method} is the method object with the given
qualifiers and specializers.  If no such method object exists,
{\bf get-method} returns {\bf nil}.

\label Examples:

\screen!

\endscreen!

\endcom



\begincom{lambda-list-specializers}

\label Purpose:

The function {\bf lambda-list-specializers} takes a {\bf
defmethod} lambda list and returns a list containing the argument
specializers for all required arguments.  The specializer {\bf t} is
returned for any lambda list argument for which no argument specializer
was given.

\label Syntax:

\Defun {lambda-list-specializers} {specialized-lambda-list}

\label Values:

The result of {\bf lambda-list-specializers} is a list of the argument
specifiers for all required arguments in the given lambda list.

\endcom


\begincom{make-generic-function}

\label Purpose:

The function {\bf make-generic-function} creates and returns a generic
function.  This resulting function can be used an argument to
{\bf funcall} and {\bf apply}.

\label Syntax:

\Defun {make-generic-function} {\key \vtop{\hbox{ :function-parameters :argument-precedence-order}
\hbox{ :method-combination-type :documentation \dots}}}

\label Arguments:

The {\bf :function-parameters} argument is a lambda list.

The {\bf :argument-precedence-order} argument is a list that is a
permutation of all the required parameters of the generic function lambda list.

The {\bf :method-combination-type} argument is a symbol.

The {\bf :documentation} argument is a string.

\label Values:

The result of {\bf make-generic-function} is a generic function object.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

The function {\bf make-generic-function} is intended to be the
programmatic interface to {\bf defgeneric}.

\label See Also:

{\bf defgeneric}

\endcom

\begincom{make-instance}

\label Purpose:

The function {\bf make-instance} creates and returns a new instance of
the class {\it class}.

\label Syntax:

\Defun {make-instance} {class {\rest} initialize-keywords-and-values}

\label Arguments:

The {\it class\/} argument is a class or a symbol that names a class.

\label Values:

The new instance is returned.

\label Remarks:

[Discussion of initialization to go here.]

The function {\bf class-of} can be used to determine the class of the
instance that is returned.

It is not possible to make an instance of a class whose class is
{\bf standard-type-class} using the function {\bf make-instance}.  
If {\it class} is an instance of {\bf standard-type-class}, 
{\bf make-instance} signals an error.

It is not possible to make an instance of class created with {\bf defclass}
if the {\bf :instantiable} option was {\bf nil}.  An error is signalled in
this case.

\label See Also:

{\bf class-of}

\endcom





\begincom{remove-class}

\label Purpose:

\label Syntax:

\Defun {remove-class} {class}

\label Arguments:

\label Values:

\label Examples:

\endcom



\begincom{remove-method}

\label Purpose:

The function {\bf remove-method} removes the method for the given
name, qualifiers, and argument specializers from the corresponding
generic function.

The method {\bf remove-method} returns the method object if it succeeds and
{\bf nil} if there is no such method.

\label Syntax:

\Defun {remove-method} {generic-function qualifiers specializers}

\label Arguments:

The {\it generic-function\/} argument is a generic function or the name
of a generic function.

The {\it qualifiers\/} argument specifies the method combination options.

The {\it specializers\/} argument is a list of the argument
specializers for the arguments of the method that is to be removed.
If the {\it specializers\/} list contains fewer elements than the
lambda list of the corresponding generic function, the remaining
elements are considered to be {\bf t}.

\label Values:

The result of {\bf remove-method} is the method object with the given
qualifiers and specializers.  If no such method object exists,
{\bf remove-method} returns {\bf nil}.

\label Examples:

\screen!

[To be written.]
\endscreen!

\label Remarks:

The {\it specializers\/} list can be obtained from a {\bf defmethod}
lambda list by use of the function {\bf lambda-list-specializers}.

\label See Also:

{\bf lambda-list-specializers

remove-setf-method

defmethod

get-method}

\endcom



\begincom{remove-setf-method}

\label Purpose:

The function {\bf remove-setf-method} removes the {\bf setf} method for
the given name, qualifiers, and argument specializers from the corresponding
generic function.

The method {\bf remove-setf-method} returns the given method object if it 
succeeds and {\bf nil} if there is no such method.

\label Syntax:

\Defun {remove-setf-method} {generic-function qualifiers specializers setf-specializers}

\label Arguments:

The {\it generic-function\/} argument is a generic function or the name
of a generic function.

The {\it qualifiers\/} argument specifies the method combination options.

The {\it specializers\/} argument is a list of
the argument specializers for the arguments of the
method that is to be removed.  If the {\it specializers\/}
list contains fewer elements than the lambda list of the corresponding
generic function, the remaining elements are considered to be {\bf t}.

The {\it specializers\/} list can be obtained from a
{\bf defmethod} lambda list by use of the function 
{\bf lambda-list-specializers}.

\label Values:

The result of {\bf remove-setf-method} is the method object with the given
qualifiers and specializers.  If no such method object exists,
{\bf remove-setf-method} returns {\bf nil}.

\label See Also:

{\bf lambda-list-specializers

remove-method

defmethod}

\endcom


\begincom{slot-value}

\label Purpose:

The function {\bf slot-value} returns the value contained in the slot
{\it slot-name\/} of the given object.

The macro {\bf setf} can be used with {\bf slot-value} to change the value
of a slot unless the slot is read-only.

\label Syntax:

\Defun {slot-value} {object slot-name}

\label Examples:

\screen!

[To be written.]
\endscreen!


\endcom


\begincom{with-slots}

\label Purpose:

The macro {\bf with-slots} creates a lexical context for using slots as
variables.  Within such a context the slot can be specified by its slot
name, as if it were a lexically bound variable.   {\bf setf} and {\bf
setq} can be used to set the value of the slot. 

The macro {\bf with-slots} translates an appearance of the slot name as
a variable into a call to the accessor generated by {\bf defclass}
(unless ({\bf :use-accessors nil}) is specified.

\label Syntax:  

(with-slots ({instance | (instance {option}*)}* form*)


\Defmac {with-slots} {\paren {\star{\curly{var-name $\vert$ varspec}}} \star{\form}}

{\it varspec\/}::$=$ {\paren {var-name {\star{\curly{options}}}}}

{\it options\/}::$=$  {\tt\vtop{\hbox{:use-accessor {\it t-or-nil\/} $\vert$}
\hbox{:class {\it class-name\/} $\vert$}
\hbox{:prefix {\it prefix-string\/}}}}

\label Arguments:

The expression {\it instance\/} must evaluate to an instance; it is
evaluated exactly once.  

It is necessary that the class of the instance can be determined.
Either {\it instance\/} must be the name of a specialized parameter in
the lambda-list of a method lexically containing this {\bf with-slots}
form, or the {\bf :class} option must be used to indicate the class of
the instance.

The recognized keywords and their arguments are:

:class class-name
                The class, or a super class, of the instance.  This option
                is necessary if the class of the instance cannot be
                determined from the lambda-list of a method lexically 
		containing this with-slots form.

:prefix prefix-string
                When you use this option you can
                reference a slot by the variable named by prefix followed
                by the slot name.  This enables you to keep separate two
                instances whose slot names overlap, such as when you want
                to access two instances of the same class, or that share a
                super-class.

:use-accessors t-or-nil
		If t, when a slot is accessed, the accessor function
		generated by defclass is used to access the slots; this
		means that any methods written for the accessor are also
		run.   t is the default.   If nil, with-slots accesses 
		the slots using slot-value instead of the accessor.
		If the {\bf defclass} form did not specifically generate 
                accessors, the ({\bf :use-accessors nil} option should be used. 

\label Values:

The value of the {\bf with-slots} form itself is whatever is returned by
the last form in its body. 

\label Examples:

\screen!

(defclass point ((x 0) (y 0)) ()
  (:accessor-prefix point-))

(defmethod move ((p point) dx dy)
  (with-slots (p)  ;; p is known as a point from the method args
    (setf x (+ x dx) y (+ y dy))))

(defmethod move ((p point) dx dy)
  (with-slots ((p :use-accessors nil))
    (setf x (+ x dx) y (+ y dy))))

(defmethod make-same-height ((p1 point) (p2 point))
;;; set the y coord of p1 to the y of p2, its reference.
;;; slots of p1 are accessed using the slot names
;;; slots of p2 are accessed using ref-<slot-name>
  (with-slots (p1 :prefix p1- (p2 :prefix p2-))
    (setf p1-y p2-y)))

(defmethod make-horizontal ((l line))
   (let ((left (left-point l)) (right (right-point l)))
     (with-slots ((left  :class point :prefix left-)
                  (right :class point :prefix right-))
       (setf left-y right-y))))

\endscreen!

\label Remarks:

The examples above use {\bf setf} with the variables inside {\bf
with-slots} forms; it is also allowed to use {\bf setq}.  Note that using
{\bf setf} or {\bf setq} with a variable name does not affect the meaning
of the slot itself.

It is an error if the class of {\it instance} cannot be inferred from the
lexical context in which it occurs.   That is, if more than one {\it
instance\/} is given, they must have disjoint sets of names for slots to
avoid ambiguity of reference, or the {\bf :prefix} option must be used
to distinguish between the names.  If any ambiguity is detected, {\bf
with-slots} signals an error.

\endcom
\endChapter
\bye